
//Copyright 1997-2009 Syrinx Development, Inc.
//This file is part of the Syrinx Web Application Framework (SWAF).
// == BEGIN LICENSE ==
//
// Licensed under the terms of any of the following licenses at your
// choice:
//
//  - GNU General Public License Version 3 or later (the "GPL")
//    http://www.gnu.org/licenses/gpl.html
//
//  - GNU Lesser General Public License Version 3 or later (the "LGPL")
//    http://www.gnu.org/licenses/lgpl.html
//
//  - Mozilla Public License Version 1.1 or later (the "MPL")
//    http://www.mozilla.org/MPL/MPL-1.1.html
//
// == END LICENSE ==
using System;
using System.Xml;
	
namespace Swaf.BizObj
{
	public interface IKeyedBizObjList : IBizObjList
	{
		/// <summary>
		/// Filters the elements of the given IBizObjList based on the
		/// criteria specified in the string passed on a call to set.
		/// </summary>
		/// <remarks>
		/// A filter is specified as a comma delimited list of field critera
		/// that determin if a bizobj is to be exposed.
		/// [filter],[filter],[filter]
		/// Examples:
		/// PrimaryAddress.State == "CA", Income > "100000"
		/// 
		/// The format of a filter is always [field name][comparor][value]
		/// 
		/// The value portion of a filter can be either a literal or a data model nameaddress.
		/// Literals are always enclosed in single/double quotes while a data model reference
		/// is not enclosed in quotes.
		/// </remarks>
		string Filter {get;set;}
		/// <summary>
		/// Given the bizobjs that made it through the filtering process, they are then sorted
		/// by the sort specified during a set.  A sort is specified as a comma delimited list of 
		/// field names.
		/// Example:
		/// State,City
		/// Specifies that the bizobjs should be sorted first by the state field, then by city field.
		/// </summary>
		string Sort {get;set;}

		/// <summary>
		/// Gets the first bizObj that matches the given value passed in sortBasedKey. The variable is
		/// a comparable value to the results of how the sort was done. If sorting by multiple fields, 
		/// then the sortBasedKey should match all the fields used concatenated as a string, otherwise the type
		/// of the field is attempted to be used directly for implementation of IComparable..
		/// </summary>
		IBizObj this[IComparable sortBasedKey] {get;}

		/// <summary>
		/// Attempts to find the first matching bizobj based on the given sort based key.  If a match isn't
		/// found, null is returned.
		/// </summary>
		/// <param name="sortBasedKey">The key to find the bizobj with.</param>
		/// <param name="nearestMatchOk">When a sort based key doesn't exactly match any given bizobj the closest
		/// next match can be returned if this is true, otherwise a null is returned.</param>
		/// <returns></returns>
		IBizObj find(IComparable sortBasedKey, bool nearestMatchOk);

		bool canChangeSortFilter{get;}
		bool sortAscending{get;set;}
	}
}
